home *** CD-ROM | disk | FTP | other *** search
/ United Public Domain Gold 2 / United Public Domain Gold 2.iso / music_utilities / pt030.dms / pt030.adf / Scheme / ext.doc < prev    next >
Text File  |  1987-06-15  |  30KB  |  1,210 lines
  1. ==============================================
  2. EXTENSIONS NOT PRESENT IN THE REVISED^3 REPORT
  3. ==============================================
  4.  
  5. Scheme
  6. Version 1.2
  7. 19-March-1988
  8.  
  9. The following summarizes features included in the system which are not
  10. defined by the "Revised^3 Report on the Algorithmic Language Scheme".
  11.  
  12.  
  13.  
  14. ================================================================================
  15.  
  16. =========================
  17. SPECIAL FORM MANIPULATION
  18. =========================
  19.  
  20.  
  21.  
  22. --------------------------------------------------------------------------------
  23. add-syntax!                        PRIMITIVE PROCEDURE
  24. (add-syntax! symbol function)
  25.  
  26. A symbol is associated with the special form whose evaluation function is
  27. given by "function".  This function will be passed the special form
  28. expression (in its entirety) and the current environment whenever the
  29. special form is encountered by the evaluator.  The result of evaluating the
  30. special form is the result returned by the function.
  31.  
  32. IN:    symbol:   symbol
  33.     function: two argument function
  34.  
  35. OUT:    #u
  36.  
  37. EXAMPLE:
  38.     :=> (add-syntax! 'rqlist (lambda (exp env) (reverse (cdr exp))))
  39.     #u
  40.  
  41.     :=> (rqlist a b c)
  42.     (c b a)
  43.  
  44.  
  45.  
  46. --------------------------------------------------------------------------------
  47. delete-syntax!                        PRIMITIVE PROCEDURE
  48. (delete-syntax! symbol)
  49.  
  50. The special form associated with the given symbol is removed from the system.
  51.  
  52. IN:    symbol:symbol
  53.  
  54. OUT:    #u
  55.  
  56. EXAMPLE:
  57.     :=> (delete-syntax! 'define)
  58.     #u
  59.  
  60.     :=> (define x 1)
  61.  
  62.     *** ERROR: unbound-variable
  63.     define
  64.  
  65.  
  66.  
  67. --------------------------------------------------------------------------------
  68. get-syntax-definitions                    PRIMITIVE PROCEDURE
  69. (get-syntax-definitions)
  70.  
  71. A copy of the system's special forms association list is returned.  The
  72. builtin special forms' evaluation functions show up as #[enigma!] objects --
  73. they are not actual procedures, but instead they are pointers to code.
  74.  
  75. IN:    ---
  76.  
  77. OUT:    association list: ((symbol . code) ...)
  78.  
  79.  
  80.  
  81. ================================================================================
  82.  
  83. =======================
  84. CONSTANTS AND VARIABLES
  85. =======================
  86.  
  87.  
  88.  
  89. --------------------------------------------------------------------------------
  90. #u                            CONSTANT
  91.  
  92. "The Unit" is the only member of the Unit domain, just as #t and #f are
  93. the two members of the Boolean domain.    It is returned from functions
  94. which would otherwise have no meaningful return value, typically those
  95. functions which cause side-effects.
  96.  
  97.  
  98.  
  99. --------------------------------------------------------------------------------
  100. command-name                        VARIABLE
  101.  
  102. This symbol is set during system initialization.  Its value is the name
  103. of the executable file invoked to start the Scheme system.  In C parlance,
  104. it is the value of argv[0].  If the program is invoked from the Workbench,
  105. command-name has the value "".
  106.  
  107. EXAMPLE:
  108.     From CLI:    1> Scheme x y z
  109.  
  110.     In Scheme:    :=> command-name
  111.             "Scheme"
  112.  
  113.  
  114.  
  115. --------------------------------------------------------------------------------
  116. command-line                        VARIABLE
  117.  
  118. This symbol is set during system initialization.  Its value is the arguments
  119. supplied on the command line when the Scheme system was started.  If the
  120. program is invoked from the Workbench, command-line has the value "".
  121.  
  122. EXAMPLE:
  123.     From CLI:    1> Scheme x y z
  124.  
  125.     In Scheme:    :=> command-line
  126.             "x y z\
  127.             "       ; note that newline character is included
  128.  
  129.  
  130.  
  131. --------------------------------------------------------------------------------
  132. startup-file                        VARIABLE
  133.  
  134. This symbol is set during system initialization.  Its value is the name of
  135. the startup file loaded into Scheme as the last step of system initialization.
  136. If the startup file was not found, startup-file has the value "".  Currently,
  137. only one filename is attempted, "S:Scheme-init.scm".
  138.  
  139.  
  140.  
  141. ================================================================================
  142.  
  143. ====================
  144. HEAP SIZE MANAGEMENT
  145. ====================
  146.  
  147.  
  148.  
  149. --------------------------------------------------------------------------------
  150. change-size                        PRIMITIVE PROCEDURE
  151. (change-size new-size)
  152.  
  153. The heap memory blocks' sizes are changed to new-size bytes.
  154.  
  155. IN:    new-size: exact integer
  156.  
  157. OUT:    ()    if failed because request was too small
  158.     #f    if failed because memory not available
  159.     #t    if successful
  160.  
  161.  
  162. --------------------------------------------------------------------------------
  163. extend-size                        PRIMITIVE PROCEDURE
  164. (extend-size amount-to-expand)
  165.  
  166. The heap memory blocks' sizes are increased by amount-to-expand bytes.
  167.  
  168. IN:    amount-to-expand: exact integer
  169.  
  170. OUT:    ()    if failed because resulting size was too small
  171.     #f    if failed because memory not available
  172.     #t    if successful
  173.  
  174.  
  175.  
  176. --------------------------------------------------------------------------------
  177. shrink-size                        PRIMITIVE PROCEDURE
  178. (shrink-size amount-to-shrink)
  179.  
  180. The heap memory blocks' sizes are decreased by amount-to-shrink bytes.
  181.  
  182. IN:    amount-to-shrink: exact integer
  183.  
  184. OUT:    ()    if failed because resulting size was too small
  185.     #f    if failed because memory not available
  186.     #t    if successful
  187.  
  188.  
  189.  
  190. --------------------------------------------------------------------------------
  191. minimize-size                        PRIMITIVE PROCEDURE
  192. (minimize-size)
  193.  
  194. The heap memory blocks' sizes are decreased to a minimum size.
  195.  
  196. IN:    ---
  197.  
  198. OUT:    #f    if failed because memory not available
  199.     #t    if successful
  200.  
  201.  
  202.  
  203. --------------------------------------------------------------------------------
  204. current-size                        PRIMITIVE PROCEDURE
  205. (current-size)
  206.  
  207. The current size in bytes of each of the heap memory blocks is returned.
  208.  
  209. IN:    ---
  210.  
  211. OUT:    size: exact integer
  212.  
  213.  
  214.  
  215. --------------------------------------------------------------------------------
  216. collect-garbage                     PRIMITIVE PROCEDURE
  217. (collect-garbage)
  218.  
  219. A garbage-collection is performed.
  220.  
  221. IN:    ---
  222.  
  223. OUT:    #u
  224.  
  225.  
  226.  
  227. ================================================================================
  228.  
  229. ==================
  230. INTERRUPT-HANDLING
  231. ==================
  232.  
  233. Unless otherwise noted in what follows, "interrupt" refers to an event
  234. within the Scheme system, and not a hardware event in the Amiga system,
  235. though Amiga interrupts may ultimately produce Scheme interrupts.
  236.  
  237. The Scheme system responds to interrupts by generating an error at the point
  238. in the process where they are first detected.  The reason passed to the error
  239. handler is the symbol INTERRUPT, and the cause is the interrupt flags value
  240. as an exact integer.
  241.  
  242. Currently, two types of interrupts are recognized by the system: breaks and
  243. hard breaks.  Breaks are caused by CTRL-C, CTRL-D and CTRL-E.  Hard breaks
  244. are caused by CTRL-F.
  245.  
  246. Amiga interrupts are handled by an exception handler associated with the
  247. Scheme task.  When the handler executes, it sets a bit associated with the
  248. event in the Scheme system's interrupt flags.  The interpreter will acts on
  249. these flags later.
  250.  
  251. In conjunction with the interrupt flags, the system maintains an interrupt
  252. mask.  This integer's bits indicate which of the interrupt flags are
  253. currently allowed to cause an interrupt.  Interrupts posted to a flag whose
  254. mask bit is 0 will be ignored until the mask bit becomes 1.
  255.  
  256. Breaks set interrupt bit 0.  Hard breaks set interrupt bit 1. Interrupt
  257. bits 0-7 are reserved for the system, and bits 8-15 are intended for the
  258. user.  There are currently only 16 interrupt bits.
  259.  
  260.  
  261.  
  262. --------------------------------------------------------------------------------
  263. current-interrupt-flags                 PRIMITIVE PROCEDURE
  264. (current-interrupt-flags)
  265.  
  266. The current state of the pending interrupt flags is returned.
  267.  
  268. IN:    ---
  269.  
  270. OUT:    flags: exact integer
  271.  
  272.  
  273.  
  274. --------------------------------------------------------------------------------
  275. set-interrupt-flags!                    PRIMITIVE PROCEDURE
  276. (set-interrupt-flags! flags-mask affect-mask)
  277.  
  278. The current state of the pending interrupt flags is modified.
  279. Only the flags indicated in affect-mask are affected; their values
  280. are set as indicated by flags mask.  This function can be used
  281. to simulate a break.
  282.  
  283. IN:    flags-mask:  exact positive integer
  284.     affect-mask: exact positive integer
  285.  
  286. OUT:    #u
  287.  
  288. EXAMPLE:
  289.     (set-interrupt-flags! 1 1)    ; simulate CTRL-C
  290.  
  291.  
  292.  
  293. --------------------------------------------------------------------------------
  294. current-interrupt-mask                    PRIMITIVE PROCEDURE
  295. (current-interrupt-mask)
  296.  
  297. The current state of the interrupt mask is returned.
  298.  
  299. IN:    ---
  300.  
  301. OUT:    mask: exact integer
  302.  
  303.  
  304.  
  305. --------------------------------------------------------------------------------
  306. with-interrupt-mask                    PRIMITIVE PROCEDURE
  307. (with-interrupt-mask mask-mask affect-mask thunk)
  308.  
  309. This function provides a controlled method of setting the value of the
  310. interrupt mask.  The bits indicated by affect-mask in the current interrupt
  311. mask are set according to the corresponding bits in mask-mask, then the
  312. thunk's body is executed.  When finished, the original mask is restored.
  313.  
  314. The mask's value is "dynamically-wound".  Any entry or exit (even if
  315. nonlocal through a continuation) will cause the mask to be set to the
  316. appropriate value.  See dynamic-wind.
  317.  
  318. IN:    mask-mask:   exact integer
  319.     affect-mask: exact integer
  320.     thunk:         0-argument procedure object
  321.  
  322. OUT:    return value from thunk
  323.  
  324. EXAMPLE:
  325.     (with-interrupt-mask #b0000000000000010 #b1111111111111111
  326.       (lambda () <critical-code>)        ; allow only hard breaks
  327.  
  328.  
  329. This function could be defined as follows, given a mythical interrupt-mask-
  330. setting function:
  331.  
  332.     (define (with-interrupt-mask mask affect-mask thunk)
  333.       (let ((old-mask (current-interrupt-mask))
  334.         (new-mask (logical-or (logical-and affect-mask mask)
  335.                       (logical-and (logical-not affect-mask)
  336.                            (current-interrupt-mask))) ))
  337.         (dynamic-wind
  338.           (lambda () (SET-INTERRUPT-MASK! new-mask))
  339.           thunk
  340.           (lambda () (SET-INTERRUPT-MASK! old-mask)) )))
  341.  
  342.  
  343.  
  344. ================================================================================
  345.  
  346. ==============
  347. ERROR HANDLING
  348. ==============
  349.  
  350. The system maintains a continuation which is called each time an error
  351. occurs. Currently, the continuation is thrown a packet (a list) of three
  352. things: the reason, the cause and a continuation of the faulted process.
  353. The format of this packet may change in the future.
  354.  
  355. For example,
  356.  
  357.     (let ((n 1) (d 0))
  358.       (if (= 0 d)
  359.           (error 'bad-value d)
  360.           (/ n d)))
  361.  
  362. will cause the error handler continuation to be invoked with the packet
  363. (bad-value 1 <cont>) where <cont> is a newly-made continuation of the
  364. process near the point of the error.
  365.  
  366. The continuations passed into the error handler are sometimes from a
  367. point prior to the actual error.  Errors occurring inside primitive
  368. procedures return to the continuation of the erroring primitive.
  369.  
  370. WARNING
  371. -------
  372. Continuations passed into the error handler whose reason is
  373. special-form-syntax-error are currently unstable.  I think all the others
  374. are OK, but if you see one from a special-form-syntax-error, DON'T USE IT.
  375. These continuations will most likely cause a system crash if applied.
  376. I will be working on this problem, but for now, error handlers (and/or
  377. debuggers) should not use special-form-syntax-error continuations.
  378.  
  379.  
  380.  
  381. --------------------------------------------------------------------------------
  382. current-error-continuation                PRIMITIVE PROCEDURE
  383. (current-error-continuation)
  384.  
  385. The current error continuation is returned.
  386.  
  387. IN:    ---
  388.  
  389. OUT:    err-cont: continuation
  390.  
  391.  
  392.  
  393. --------------------------------------------------------------------------------
  394. error-context                        PRIMITIVE PROCEDURE
  395. (error-context error-handler-continuaton body-thunk)
  396.  
  397. This function provides a controlled method of installing a new error
  398. continuation.  The body-thunk is executed with this new handler in place.
  399. When finished, the original handler is restored.
  400.  
  401. The error handler continuation is "dynamically-wound".  Any entry or exit
  402. (even if nonlocal through another continuation) will cause the handler to
  403. be set appropriately.  See dynamic-wind.
  404.  
  405. IN:    error-handler-continuation: continuation
  406.     thunk: 0-argument procedure object
  407.  
  408. OUT:    return value from thunk
  409.  
  410. EXAMPLE:
  411.     :=> (define ec
  412.           (call/cc
  413.         (lambda (return)
  414.           (display (call/cc
  415.                  (lambda (later)
  416.                    (return later))))
  417.           (newline))))
  418. returns --> ec
  419.  
  420.     :=> (error-context ec
  421.           (lambda ()
  422.         (let ((n 1) (d 0))
  423.           (if (= 0 d)
  424.               (error 'bad-value d)
  425.               (/ n d)))))
  426.  prints --> (bad-value 0 #[closure])
  427. returns --> ec
  428.  
  429.     :=> ec
  430. returns --> #u
  431.  
  432. This function could be defined as follows, given a mythical error-handler-
  433. setting function:
  434.  
  435.     (define (error-context error-handler-continuation body-thunk)
  436.       (let ((old-handler (current-error-continuation)))
  437.         (dynamic-wind
  438.           (lambda () (SET-ERROR-HANDLER! error-handler-continuation))
  439.           body-thunk
  440.           (lambda () (SET-ERROR-HANDLER! old-handler)) )))
  441.  
  442.  
  443.  
  444. --------------------------------------------------------------------------------
  445. error                            PRIMITIVE PROCEDURE
  446. (error reason cause)
  447.  
  448. Generate an error.  The current error handler will be thrown the reason and
  449. cause along with a continuation of the current process.
  450.  
  451.  
  452.  
  453. ================================================================================
  454.  
  455. ==============================
  456. MISCELLANEOUS SYSTEM FUNCTIONS
  457. ==============================
  458.  
  459.  
  460.  
  461. --------------------------------------------------------------------------------
  462. abort-system                        PRIMITIVE PROCEDURE
  463. (abort-system)
  464. (abort-system exitval)
  465.  
  466. The Scheme system is aborted.  If exitval is supplied, it is the return
  467. value returned to AmigaDOS.  Otherwise, 0 is returned.
  468.  
  469. IN:    exitval: exact integer (optional)
  470.  
  471. OUT:    nothing!
  472.  
  473.  
  474.  
  475. --------------------------------------------------------------------------------
  476. file-exists?                        PRIMITIVE PROCEDURE
  477. (file-exists? filename)
  478.  
  479. This function returns whether or not a file could be Lock()'ed.
  480. The file is not left in a locked state, however.
  481.  
  482. IN:    filename: string
  483.  
  484. OUT:    boolean
  485.  
  486.  
  487.  
  488. --------------------------------------------------------------------------------
  489. sleep                            PRIMITIVE PROCEDURE
  490. (sleep nticks)
  491.  
  492. The system sleeps for roughly nticks/50 seconds.
  493.  
  494. IN:    nticks: exact integer
  495.  
  496. OUT:    #u
  497.  
  498.  
  499.  
  500. --------------------------------------------------------------------------------
  501. call-system                        PRIMITIVE PROCEDURE
  502. (call-system command)
  503.  
  504. The command is issued via an AmigaDOS Execute() call.
  505.  
  506. IN:    command: string
  507.  
  508. OUT:    boolean
  509.  
  510.  
  511.  
  512. ================================================================================
  513.  
  514. ===
  515. I/O
  516. ===
  517.  
  518.  
  519.  
  520. --------------------------------------------------------------------------------
  521. read-raw-bytes                        PRIMITIVE PROCEDURE
  522. (read-raw-bytes size)
  523. (read-raw-bytes size port)
  524.  
  525. An attempt is made to read the number of bytes specified by "size", and a
  526. string is returned formed by those which were read.  The length of the
  527. returned string is the number of bytes actually read.  If the port argument
  528. is not supplied, the current input port is used.
  529.  
  530. The number of bytes read will be less than "size" if an end-of-file is
  531. encountered.  If the file is at end-of-file when read-raw-bytes is called,
  532. an empty string will be returned.
  533.  
  534. Interactive files sometimes return fewer bytes as the result of a newline.
  535.  
  536. IN:    size: exact integer
  537.     port: port (optional)
  538.  
  539. OUT:    string
  540.  
  541.  
  542.  
  543. --------------------------------------------------------------------------------
  544. write-raw-bytes                     PRIMITIVE PROCEDURE
  545. (write-raw-bytes string)
  546. (write-raw-bytes string port)
  547.  
  548. The text of the given string is written in raw format to "port", or to the
  549. current output port if no port argument is supplied.
  550.  
  551. IN:    string: string
  552.     port:    port (optional)
  553.  
  554. OUT:    #u
  555.  
  556.  
  557.  
  558. ================================================================================
  559.  
  560. ===================
  561. LOW-LEVEL ACCESSORS
  562. ===================
  563.  
  564. These functions allow access to the low-level representations of objects.
  565. Some are dangerous, and can cause system crashes if used improperly.
  566. These have names prefixed with "!".
  567.  
  568. In the descriptions below, "rep" values are of the form (tags . value).
  569. Both tags and value are exact integers.
  570.  
  571.  
  572.  
  573. --------------------------------------------------------------------------------
  574. obj->rep                        PRIMITIVE PROCEDURE
  575. (obj->rep obj)
  576.  
  577. The representation of obj is returned.
  578.  
  579. IN:    obj: any Scheme object
  580.  
  581. OUT:    (tags . value)
  582.  
  583. EXAMPLE:
  584.     :=> (obj->rep '())
  585.     (130 . 1)
  586.  
  587.  
  588.  
  589. --------------------------------------------------------------------------------
  590. !rep->obj                        PRIMITIVE PROCEDURE
  591. (!rep->obj rep)
  592.  
  593. An object is returned, assuming that the tags and value describe a valid
  594. object.  This can cause a crash if you introduce bad stuff into the system.
  595.  
  596. IN:    (tags . value)
  597.  
  598. OUT:    an object
  599.  
  600. EXAMPLE:
  601.     :=> (!rep->obj '(130 . 1))
  602.     ()
  603.  
  604.  
  605.  
  606. --------------------------------------------------------------------------------
  607. !storage-ref                        PRIMITIVE PROCEDURE
  608. (!storage-ref obj offset)
  609.  
  610. Given that the rep of obj is (tags . value), the object stored at memory
  611. location (+ value (* 4 offset)) is returned.
  612.  
  613. IN:    obj:    any object
  614.     offset: exact integer
  615.  
  616. OUT:    an object
  617.  
  618. EXAMPLE:
  619.     :=> (!storage-ref '(a b) 0)
  620.     (b)
  621.  
  622.     :=> (!storage-ref '(a b) 1)
  623.     a
  624.  
  625.  
  626.  
  627. --------------------------------------------------------------------------------
  628. !storage-set!                        PRIMITIVE PROCEDURE
  629. (!storage-set! obj offset obj-to-store)
  630.  
  631. Given that the rep of obj is (tags . value), obj-to-store is stored
  632. at memory location (+ value (* 4 offset)).
  633.  
  634. IN:    obj:          any object
  635.     offset:       exact integer
  636.     obj-to-store: any object
  637.  
  638. OUT:    #u
  639.  
  640. EXAMPLE:
  641.     :=> (define obj '(a b))
  642.     obj
  643.  
  644.     :=> (!storage-set! obj 0 'c)
  645.     #u
  646.  
  647.     :=> obj
  648.     (a . c)
  649.  
  650.  
  651.  
  652. --------------------------------------------------------------------------------
  653. !storage-rep-ref                    PRIMITIVE PROCEDURE
  654. (!storage-rep-ref obj offset)
  655.  
  656. Given that the rep of obj is (tags . value), the rep of the object stored
  657. at memory location (+ value (* 4 offset)) is returned.    This function is
  658. slightly safer than !storage-ref!...you will not pollute the system with
  659. non-objects.
  660.  
  661. IN:    obj:    any object
  662.     offset: exact integer
  663.  
  664. OUT:    (tags . value) for referenced object
  665.  
  666. EXAMPLE:
  667.     :=> (!storage-rep-ref '(() . b) 1)
  668.     (130 . 1)
  669.  
  670.  
  671.  
  672. --------------------------------------------------------------------------------
  673. !storage-rep-set!                    PRIMITIVE PROCEDURE
  674. (!storage-rep-set! obj offset rep-to-store)
  675.  
  676. Given that the rep of obj is (tags . value), obj-to-store is stored
  677. at memory location (+ value (* 4 offset)).
  678.  
  679. IN:    obj:          any object
  680.     offset:       exact integer
  681.     rep-to-store: (tags . value)
  682.  
  683. OUT:    #u
  684.  
  685. EXAMPLE:
  686.     :=> (define obj '(a b))
  687.     obj
  688.  
  689.     :=> (!storage-rep-set! obj 0 '(130 . 1))
  690.     #u
  691.  
  692.     :=> obj
  693.     (a)
  694.  
  695.  
  696.  
  697. --------------------------------------------------------------------------------
  698. !byte-ref                        PRIMITIVE PROCEDURE
  699. (!byte-ref obj offset)
  700.  
  701. Given that the rep of obj is (tags . value), the byte stored at memory
  702. location (+ value offset) is returned.
  703.  
  704. IN:    obj:    any object
  705.     offset: exact integer
  706.  
  707. OUT:    byte: exact integer
  708.  
  709. EXAMPLE:
  710.     :=> (!byte-ref '(a . ()) 0)
  711.     130
  712.  
  713.  
  714.  
  715. --------------------------------------------------------------------------------
  716. !byte-set!                        PRIMITIVE PROCEDURE
  717. (!byte-set! obj offset byte)
  718.  
  719. Given that the rep of obj is (tags . value), byte is stored at
  720. memory location (+ value offset).
  721.  
  722. IN:    obj:    any object
  723.     offset: exact integer
  724.     byte:    any object
  725.  
  726. OUT:    #u
  727.  
  728. EXAMPLE:
  729.     :=> (define obj (a . 0))
  730.     obj
  731.  
  732.     :=> (!byte-set! obj 3 7)
  733.     #u
  734.  
  735.     :=> obj
  736.     (a . 7)
  737.  
  738.  
  739.  
  740. ================================================================================
  741.  
  742. ===========================
  743. PROCEDURE OBJECT TYPE TESTS
  744. ===========================
  745.  
  746. The following tests further subdivide the class of objects for which
  747. procedure? returns #t.
  748.  
  749.  
  750.  
  751. --------------------------------------------------------------------------------
  752. primitive?                        PRIMITIVE PROCEDURE
  753. (primitive? obj)
  754.  
  755. IN:    obj: any object
  756.  
  757. OUT:    #t if obj is a primitive procedure
  758.     #f otherwise
  759.  
  760.  
  761.  
  762. --------------------------------------------------------------------------------
  763. compound-procedure?                    PRIMITIVE PROCEDURE
  764. (compound-procedure? obj)
  765.  
  766. IN:    obj: any object
  767.  
  768. OUT:    #t if obj is a compound procedure (produced by lambda)
  769.     #f otherwise
  770.  
  771.  
  772.  
  773. --------------------------------------------------------------------------------
  774. compiled?                        PRIMITIVE PROCEDURE
  775. (compiled? obj)
  776.  
  777. Currently, no system functions produce compiled procedure objects.
  778.  
  779. IN:    obj: any object
  780.  
  781. OUT:    #t if obj is a compiled procedure
  782.     #f otherwise
  783.  
  784.  
  785.  
  786. --------------------------------------------------------------------------------
  787. thunk?                            PRIMITIVE PROCEDURE
  788. (thunk? obj)
  789.  
  790. Currently, no external system functions produce thunk objects.
  791. The system's thunk type is not merely a procedure of 0 arguments,
  792. but a special 0-argument procedure type used internally.
  793.  
  794. IN:    obj: any object
  795.  
  796. OUT:    #t if obj is a    procedure
  797.     #f otherwise
  798.  
  799.  
  800.  
  801. --------------------------------------------------------------------------------
  802. promise?                        PRIMITIVE PROCEDURE
  803. (promise? obj)
  804.  
  805. IN:    obj: any object
  806.  
  807. OUT:    #t if obj is a promise (0-argument procedure returned by delay)
  808.     #f otherwise
  809.  
  810.  
  811.  
  812. --------------------------------------------------------------------------------
  813. continuation?                        PRIMITIVE PROCEDURE
  814. (continuation? obj)
  815.  
  816. IN:    obj: any object
  817.  
  818. OUT:    #t if obj is a continuation
  819.     #f otherwise
  820.  
  821.  
  822.  
  823. ================================================================================
  824.  
  825. =============
  826. MISCELLANEOUS
  827. =============
  828.  
  829.  
  830.  
  831. --------------------------------------------------------------------------------
  832. eval                            PRIMITIVE PROCEDURE
  833. (eval exp env)
  834.  
  835. The expression is evaluated in the given environment, and the result returned.
  836.  
  837. IN:    exp: a Scheme expression
  838.     env: an environment object
  839.  
  840. OUT:    the result of evaluating exp in env
  841.  
  842. EXAMPLE:
  843.     :=> (eval '(+ 2 3) (the-environment))
  844.     5
  845.  
  846.  
  847.  
  848. --------------------------------------------------------------------------------
  849. dynamic-wind                        PRIMITIVE PROCEDURE
  850. (dynamic-wind entry-thunk body-thunk exit-thunk)
  851.  
  852. This function provides a controlled method of ensuring the dynamic state of
  853. a process.  The entry-thunk's code is executed, then the body-thunk's code
  854. and finally the exit-thunk's code.  The result is that which was returned
  855. by body-thunk.
  856.  
  857. Any exit, local or nonlocal, causes the exit-thunk to be applied.
  858. Any entry, local or nonlocal, causes the entry-thunk to be applied.
  859. The entry and exit thunks are applied with the interrupt mask
  860. set to accept hard breaks only.  It will probably cause problems if
  861. an entry or exit thunk is interrupted.
  862.  
  863. IN:    entry-thunk: 0-argument procedure object
  864.     body-thunk:  0-argument procedure object
  865.     exit-thunk:  0-argument procedure object
  866.  
  867. OUT:    return value from body-thunk
  868.  
  869. EXAMPLE:
  870.     :=> (define dwind-test
  871.           (dynamic-wind
  872.         (lambda () (display "ENTRY") (newline))
  873.         (lambda () (call/cc (lambda (cont) cont)))
  874.         (lambda () (display "EXIT") (newline))))
  875.  prints --> ENTRY
  876.  prints --> EXIT
  877. returns --> dwind-test
  878.  
  879.     :=> (define wound-cont dwind-test)  ; 'cause dwind-test gets clobbered
  880.     wound-cont
  881.  
  882.     :=> (wound-cont 'hello)
  883.  prints --> ENTRY
  884.  prints --> EXIT
  885. returns --> dwind-test
  886.  
  887.     :=> dwind-test
  888. returns --> hello
  889.  
  890.     :=> (wound-cont 'aloha)
  891.  prints --> ENTRY
  892.  prints --> EXIT
  893. returns --> dwind-test
  894.  
  895.     :=> dwind-test
  896. returns --> aloha
  897.  
  898.  
  899.  
  900. --------------------------------------------------------------------------------
  901. char->string                        PRIMITIVE PROCEDURE
  902. (char->string char)
  903.  
  904. A string representing the given character is returned.    The string is such
  905. that the reader operating on it would return the given character.
  906.  
  907. IN:    char: character
  908.  
  909. OUT:    string: a string formed by prepending #\ to a character specifier:
  910.  
  911.     (char->integer char)    character specifier
  912.     --------------------    -------------------
  913.         #x00            nul
  914.         #x01            soh
  915.         #x02            stx
  916.         #x03            etx
  917.         #x04            eot
  918.         #x05            enq
  919.         #x06            ack
  920.         #x07            bel
  921.         #x08            bs
  922.         #x09            ht
  923.         #x0A            lf
  924.         #x0B            vt
  925.         #x0C            ff
  926.         #x0D            cr
  927.         #x0E            so
  928.         #x0F            si
  929.         #x10            dle
  930.         #x11            dc1
  931.         #x12            dc2
  932.         #x13            dc3
  933.         #x14            dc4
  934.         #x15            nak
  935.         #x16            syn
  936.         #x17            etb
  937.         #x18            can
  938.         #x19            em
  939.         #x1A            sub
  940.         #x1B            esc
  941.         #x1C            fs
  942.         #x1D            gs
  943.         #x1E            rs
  944.         #x1F            us
  945.         #x20            space
  946.       #x21 through #x7E        the character
  947.         #x7F            rub
  948.       #x80 through #xFF        the character
  949.  
  950. EXAMPLE:
  951.     :=> (char->string #\space)
  952.     "#\\space"      ; \ is escaped
  953.  
  954.  
  955.  
  956. --------------------------------------------------------------------------------
  957. string->char                        PRIMITIVE PROCEDURE
  958. (string->char string)
  959.  
  960. A string representation of a character (such as char->string would return)
  961. is converted to its corresponding character.  Character case is ignored.
  962. In addition, the following strings are recognized:
  963.  
  964.     "#\\null"       --> #\nul
  965.     "#\\bell"       --> #\bel
  966.     "#\\tab"        --> #\ht
  967.     "#\\newline"    --> #\lf
  968.  
  969. Unrecognized strings cause #u to be returned.
  970.  
  971. IN:    string: string
  972.  
  973. OUT:    char: character if successful
  974.     #u if unsuccessful
  975.  
  976.  
  977.  
  978. --------------------------------------------------------------------------------
  979. call-with-quotient&remainder                PRIMITIVE PROCEDURE
  980. (call-with-quotient&remainder number1 number2 proc)
  981.  
  982. This function lets you get both the quotient and the remainder with one call.
  983.  
  984. IN:    number1: number
  985.     number2: number
  986.     proc:     2-argument procedure
  987.  
  988. OUT:    return value from proc
  989.  
  990. EXAMPLE:
  991.     :=> (call-with-quotient&remainder 229 11
  992.           (lambda (q r)
  993.         (display (cons q r))))
  994.     (20 . 9)#u
  995.  
  996.  
  997.  
  998. --------------------------------------------------------------------------------
  999. fluid-let                        SPECIAL FORM
  1000. (fluid-let (binding1 ...) exp1 ...)
  1001. (fluid-let () exp1 ...)
  1002.  
  1003. This special form is just like the "let" special form, except that the
  1004. bindings are dynamic instead of static.  It is unlike MIT Scheme's fluid-let
  1005. in that the bindings are in a separate environment, and must be accessed
  1006. with the special form "fluid".
  1007.  
  1008. EXAMPLE:
  1009.  
  1010.     :=> (define (p x)
  1011.           (cons x (fluid x)))
  1012.         p
  1013.  
  1014.     :=> (fluid-let ((x 'fluid-var))
  1015.           (p 'lexical-var))
  1016.         (lexical-var . fluid-var)
  1017.  
  1018.  
  1019.  
  1020. --------------------------------------------------------------------------------
  1021. fluid                            SPECIAL FORM
  1022. (fluid symbol)
  1023.  
  1024. This special form provides access to variables in the fluid environment.
  1025.  
  1026.  
  1027.  
  1028. ================================================================================
  1029.  
  1030. =======
  1031. STREAMS
  1032. =======
  1033.  
  1034.  
  1035.  
  1036. --------------------------------------------------------------------------------
  1037. the-empty-stream                    VARIABLE
  1038.  
  1039. This is a distinguished object representing the empty stream.
  1040. (stream? the-empty-stream) returns #t.
  1041.  
  1042.  
  1043.  
  1044. --------------------------------------------------------------------------------
  1045. stream?                         PRIMITIVE PROCEDURE
  1046. (stream? obj)
  1047.  
  1048. IN:    obj: any object
  1049.  
  1050. OUT:    #t if obj is a stream object
  1051.     #f otherwise
  1052.  
  1053.  
  1054.  
  1055. --------------------------------------------------------------------------------
  1056. empty-stream?                        PRIMITIVE PROCEDURE
  1057. (empty-stream? obj)
  1058.  
  1059. IN:    obj: any object
  1060.  
  1061. OUT:    #t if obj is the-empty-stream
  1062.     #f otherwise
  1063.  
  1064.  
  1065. --------------------------------------------------------------------------------
  1066. cons-stream                        SPECIAL FORM
  1067. (cons-stream obj1 obj2)
  1068.  
  1069. A stream object is returned whose "head" is obj1 and "tail" is obj2.  Obj1
  1070. is evaluated prior to building the stream object, obj2 is not evaluated
  1071. until a "tail" is performed on the stream object.  Even so, obj2 will be
  1072. evaluated but once; it is memoized.
  1073.  
  1074. IN:    obj1: any object
  1075.     obj2: any object
  1076.  
  1077. OUT:    stream object
  1078.  
  1079.  
  1080.  
  1081. --------------------------------------------------------------------------------
  1082. head                            PRIMITIVE PROCEDURE
  1083. (head stream)
  1084.  
  1085. IN:    stream: stream
  1086.  
  1087. OUT:    an object
  1088.  
  1089. EXAMPLE:
  1090.     :=> (define s
  1091.           (cons-stream
  1092.         (begin (display "HEAD") (newline))
  1093.         (begin (display "TAIL") (newline))))
  1094.  prints --> "HEAD"
  1095. returns --> s
  1096.  
  1097.     :=> (head s)
  1098. returns --> #u
  1099.  
  1100.  
  1101.  
  1102. --------------------------------------------------------------------------------
  1103. tail                            PRIMITIVE PROCEDURE
  1104. (tail stream)
  1105.  
  1106. IN:    stream: stream
  1107.  
  1108. OUT:    an object
  1109.  
  1110. EXAMPLE:
  1111.     :=> (define s
  1112.           (cons-stream
  1113.         (begin (display "HEAD") (newline))
  1114.         (begin (display "TAIL") (newline))))
  1115.  prints --> "HEAD"
  1116. returns --> s
  1117.  
  1118.     :=> (tail s)
  1119.  prints --> "TAIL"
  1120. returns --> #u
  1121.  
  1122.     :=> (tail s)
  1123. returns --> #u        ; note memoization
  1124.  
  1125.  
  1126.  
  1127. ================================================================================
  1128.  
  1129. ============
  1130. ENVIRONMENTS
  1131. ============
  1132.  
  1133.  
  1134.  
  1135. --------------------------------------------------------------------------------
  1136. the-environment                     SPECIAL FORM
  1137. (the-environment)
  1138.  
  1139. This special form returns the current environment from the point where it
  1140. is evaluated.
  1141.  
  1142. EXAMPLE:
  1143.     :=> (let ((a 'first))
  1144.           (let ((env (the-environment)))
  1145.         (let ((a 'second))
  1146.           (cons a (eval 'a env)))))
  1147.     (second . first)
  1148.  
  1149.  
  1150.  
  1151. --------------------------------------------------------------------------------
  1152. environment?                        PRIMITIVE PROCEDURE
  1153. (environment? obj)
  1154.  
  1155. IN:    obj: any object
  1156.  
  1157. OUT:    #t if obj is an environment object
  1158.     #f otherwise
  1159.  
  1160.  
  1161.  
  1162. --------------------------------------------------------------------------------
  1163. make-environment                    SPECIAL FORM
  1164. (make-environment exp1 ...)
  1165.  
  1166. The given expressions are evaluated in order in a separate environment
  1167. enclosed by the current environment, and the resulting environment
  1168. is returned.
  1169.  
  1170. (make-environment exp1 ...) is equivalent to (let () exp1 ... (the-environment))
  1171.  
  1172. IN:    exps: Scheme expressions
  1173.  
  1174. OUT:    resulting environment object
  1175.  
  1176.  
  1177.  
  1178. --------------------------------------------------------------------------------
  1179. access                            SPECIAL FORM
  1180. (access symbol1 env)
  1181. (access symbol1 symbol2 ... env)
  1182.  
  1183. Symbol1 is looked up in the environment bound to symbol2 which is looked up
  1184. in the enviroment bound to ... which is looked up in the enviroment
  1185. bound to env.  At least one symbol must be specified as in
  1186. (access 'a (the-environment)).
  1187.  
  1188. IN:    symbols: symbol
  1189.     env:     environment object
  1190.  
  1191. OUT:    the value bound to symbol1
  1192.  
  1193. EXAMPLE:
  1194.     :=> (define package
  1195.           (make-environment
  1196.         (define a 'one)
  1197.         (define inner-package
  1198.           (make-environment
  1199.             (define a 'two)
  1200.             (define inner-inner-package
  1201.               (make-environment
  1202.             (define a 'three) )) )) ))
  1203.     package
  1204.  
  1205.     :=> (vector (access a package)
  1206.             (access a inner-package package)
  1207.             (access a inner-inner-package inner-package package))
  1208.     #(one two three)
  1209.  
  1210.